docs: split monolithic README into structured docs/ tree#22
Merged
Conversation
README drops from 783 to ~90 lines: pitch, install, quick start, readonly guarantee, and a navigation table into docs/. New docs/ layout (index at docs/README.md): - installation.md krew/go/source, Cilium compat matrix, k9s plugin - getting-started.md live capture, offline replay, audit onboarding - policy-generation.md pipeline, YAML examples, labels, dedup, skips - l7-guide.md L7 prerequisites, visibility bootstrap - explain.md cpg explain + evidence storage - security.md readonly model, audit-window RBAC - mcp-server.md tool catalog, harness config, agent tooling - cli-reference.md flags, dry-run, exit codes, CI integration - development.md project structure, make targets, scorecard Doc-parity tripwire tests (audit_docs, readme_compat, skills) now pin the moved prose in its new docs/ home, and the VIS-01 runtime hint points at docs/l7-guide.md instead of the removed README anchor. Cross-references in bootstrap-runbook.md, KNOWN_LIMITATIONS.md, and cpg-policy-review SKILL.md updated to the new locations.
The bootstrap runbook covers the step-by-step procedure but nothing explained how the pieces work: docs/audit-mode.md documents the per-endpoint PolicyAuditMode model, the three v1.6 building blocks (bootstrap / audit-window / --include-audit + MCP include_audit), the audit-window lifecycle guarantees (TTL-bounded, revert on every exit path, pre-existing state untouched, stuck-revert reporting), the new-endpoint race, RBAC step-up, the AUD-01 empty-audit warning, and the per-capability Cilium version floors. Linked from README, docs index, getting-started, and security model.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/docs/tree with index (docs/README.md), organized by user journey: getting started → guides → referencedocs/audit-mode.mdconcept guide for the v1.6 audit milestone (the runbook stays the step-by-step procedure)audit_docs_test.go,readme_compat_test.go,skills_test.go) repointed to the moved prose; VIS-01 runtime hint now referencesdocs/l7-guide.mdinstead of the removed README anchorbootstrap-runbook.md,KNOWN_LIMITATIONS.md, and thecpg-policy-reviewskillTest plan
go test ./... -count=1 -racegreen🤖 Generated with Claude Code
https://claude.ai/code/session_01UrP1o86545Nu9skZJq9BVY